SMTP/POP3 Email Engine Library for Visual FoxPro (SEE4FP) REFERENCE MANUAL Version 3.0 June 10, 1999 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1999 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice : 256-881-4630 FAX : 256-880-0925 email : info@marshallsoft.com web : www.marshallsoft.com _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER MARSHALLSOFT is a registered trademark of MarshallSoft Computing. SEE4FP Reference Manual Page 1 C O N T E N T S Chapter Page Table of Contents.............................2 General Remarks...............................3 SEE Functions.................................3 seeAttach..................................3 seeClose...................................4 seeDebug...................................5 seeDecodeBuffer............................6 seeDeleteEmail.............................7 seeDriver..................................8 seeEncodeBuffer............................9 seeErrorText..............................10 seeExtractText............................11 seeGetEmailCount..........................12 seeGetEmailFile...........................13 seeGetEmailLines..........................14 seeGetEmailSize...........................15 seeGetEmailUID............................16 seeIntegerParam...........................17 seePop3Connect............................19 seeRelease................................20 seeSendEmail..............................21 seeSmtpConnect............................22 seeStatistics.............................23 seeStringParam............................24 seeVerifyFormat...........................25 seeVerifyUser.............................26 SEE4FP Reference Manual Page 2 General Remarks All functions return an integer code. Negative values are always errors. See Section 10.3 "SEE Error Return Code List" in the SEE/POP3 Users Manual (SEE4FP_U.TXT). Non-negative return codes are never errors. This declaration file is for 32-bit Visual FoxPro. If 16-bit FoxPro is being used (before version FoxPro 3.0), replace CINT with CLONG as shown in SEE16.CC. Also note that arguments passed as CSTRING's must be preceeded with the '@' symbol. For example, Code = seeErrorText(0, Code, @Buffer, 64) In the code following, C style comments (//) are used to improve clarity. SEE4FP Functions +-----------+-------------------------------------------------------+ | seeAttach | Attach SMTP/POP3 Email Engine. | +-----------+-------------------------------------------------------+ SYNTAX CLONG seeAttach(CLONG,CSTRING) // CLONG NbrChans : Number of channels or threads // CSTRING KeyCode : Key code value. REMARKS The seeAttach function must be the first SEE call made. Pass the maximum number of channels or threads that will be in use. Use NbrChans = 1 for non-threaded applications. The 'Chan' parameter for subsequent calls to SEE functions must be in the range of 0 to NbrChans-1. In WIN32, up to 128 threads (numbered from 0 to 127) can be started, each of which can be connected to a different server and run independently. When SEE is registered, you will receive a 'KeyCode' which matches the 'KeyCode' within the registered DLL. For the shareware version, the keycode is 0. RETURNS < 0 : An error has occurred. See the error list. EXAMPLE // attach for use with non-threaded application Code = seeAttach(1, SEE_KEY_CODE) ALSO SEE seeSmtpConnect and seePop3Connect. SEE4FP Reference Manual Page 3 +----------+--------------------------------------------------------+ | seeClose | Closes SMTP/POP3 Email Engine. | +----------+--------------------------------------------------------+ SYNTAX CLONG seeClose(CLONG) // CLONG Chan : channel number REMARKS The seeClose function closes the connection created by calling seeSmtpConnect or seePop3Connect. seeSmtpConnect or seePop3Connect can be called again to open a connection to another SMTP or POP3 server if desired. SEE can not be connected to both the SMTP server and the POP3 server at the same time (using the same thread). Call seeClose to terminate one connection before connecting again. RETURNS < 0 : An error has occurred. See the error list. EXAMPLE // attach SEE Code = seeAttach(1, SEE_KEY_CODE) // connect to SMTP server Code = seeSmtpConnect(...) // send email with seeSendEmail . . . // close connection to SMTP server Code = seeClose(0) // connect to POP3 server Code = seePop3Connect(...) // check/read/delete our email as needed . . . // close connection to POP3 server Code = seeClose(0) // release SEE Code = seeRelease ALSO SEE seeSmtpConnect and seePop3Connect. SEE4FP Reference Manual Page 4 +----------+--------------------------------------------------------+ | seeDebug | Returns debug information. | +----------+--------------------------------------------------------+ SYNTAX CLONG seeDebug(CLONG,CLONG,CSTRING,CLONG) // CLONG Chan : Channel // CLONG Index : Command index. // CSTRING @Buffer: Buffer to place text into. // CLONG BufLen : Length of above Buffer. REMARKS The seeDebug function returns debug information depending on the value of Index. SEE_GET_REGISTRATION : Gets the registration string. SEE_GET_LAST_RESPONSE : Gets last server response. SEE_GET_SERVER_IP : Gets server IP address in "dotted" notation. RETURNS Length of text placed into *Buffer*. EXAMPLE // Get the registration string from SEE32.DLL. Buffer = SPACE(128) Code = seeDebug(0, SET_GET_REGISTRATION, @Buffer, 128) ? "Registration: " + Left(Buffer,Code) // Also see the SEEVER example program. ALSO SEE seeStatistics. SEE4FP Reference Manual Page 5 +-----------------+-------------------------------------------------+ | seeDecodeBuffer | Decodes buffer using BASE64. | +-----------------+-------------------------------------------------+ SYNTAX CLONG seeDecodeBuffer(CSTRING,CSTRING,CLONG) // CSTRING @Coded : Buffer of BASE64 coded chars. // CSTRING @Clear : Buffer to put decoded bytes. // CLONG Length : Length of 'Coded' buffer. REMARKS The seeDecodeBuffer function decodes the buffer 'Coded' of length 'Length' into 'Clear', returning the length in 'Clear'. The buffer 'Coded' MUST contain BASE64 encoded text, as created by seeEncodeBuffer. The buffer 'Clear' will contain the ASCII or binary data that was encoded. RETURNS Number of bytes placed in 'Clear'. EXAMPLE ClearBuffOne = SPACE(100) ClearBuffTwo = SPACE(100) CodedBuff = SPACE(134) NL = SPACE(2) NL = Chr(13) + Chr(10) ClearBuffOne = "SEE/POP3 Test" + NL + "Bye." + NL + Chr(0) Length = Len(ClearBuffOne) // BASE64 encode Length = seeEncodeBuffer(@ClearBuffOne,@CodedBuff, Length) // BASE64 decode Length = seeDecodeBuffer(@CodedBuff,@ClearBuffTwo, Length) // ClearBuffTwo should have same text as ClearBuffOne ALSO SEE seeEncodeBuffer. SEE4FP Reference Manual Page 6 +----------------+--------------------------------------------------+ | seeDeleteEmail | Deletes email from Server. | +----------------+--------------------------------------------------+ SYNTAX CLONG seeDeleteEmail(CLONG,CLONG) // CLONG Chan : Channel // CLONG MsgNbr : message number REMARKS The seeDeleteEmail function deletes the email numbered 'MsgNbr' from the server. Note that the first email message is numbered 1. Be careful! Once an email has been deleted from the server, it cannot be recovered. RETURNS < 0 : An error has occurred. See the error list. EXAMPLE . . . ' delete message # 5 , # 6, and #7. Code = seeDeleteEmail(0, 5) if Code >= 0 Code = seeDeleteEmail(0, 6) endif if Code >= 0 Code = seeDeleteEmail(0, 7) endif . . . ALSO SEE seeGetEmailCount and seeGetEmailUID. SEE4FP Reference Manual Page 7 +-----------+-------------------------------------------------------+ | seeDriver | Executes next SEE state. | +-----------+-------------------------------------------------------+ SYNTAX CLONG seeDriver(CLONG) // CLONG Chan : Channel REMARKS The seeDriver function executes the next state in the SEE state engine. The purpose of this function is to allow the programmer to get control after the driver executes each SEE state. The seeDriver function is explicitly called only after the AUTO_DRIVER_CALL flag has been disabled (see function seeIntegerParam). If the AUTO_DRIVER_CALL flag has not been disabled (the default), then seeDriver does not need to be called. Refer to the section 4.0 "Theory of Operation" in the SMTP/POP3 Users Manual for more details on the operation of seeDriver. RETURNS = 0 : The driver is done. < 0 : An error has occurred. See the error list. > 0 : The returned value is the state just executed. EXAMPLE Code . . . Code = seeSmtpConnect(...) . . . // disable automatic calling of seeDriver(). Code = seeIntegerParam(0, AUTO_DRIVER_CALL, 0) Code = seeSendEmail(...) if Code< 0 ? "Error " + Str(Code) return endif do while Code > 0 Code = seeDriver(0) if Code < 0 ? "Error " + Str(Code) return endif if Code = 0 return endif // do something here . . . enddo ALSO SEE seeIntegerParam, seeSmtpConnect, and seePop3Connect. SEE4FP Reference Manual Page 8 +-----------------+-------------------------------------------------+ | seeEncodeBuffer | Encodes buffer using BASE64. | +-----------------+-------------------------------------------------+ SYNTAX CLONG seeEncodeBuffer(CSTRING,CSTRING,CLONG) // CSTRING @Clear : Buffer to put decoded bytes. // CSTRING @Coded : Buffer to put BASE64 encoded. // CLONG Length : Length of 'Clear' buffer. REMARKS The seeEncodeBuffer function encodes 'Clear' into 'Coded' using Base-64 encoding. The 'Clear' buffer may contain any ASCII or binary data. The 'Coded' buffer will contain 7-bit ASCII data broken into lines of 76 characters followed by a carriage return Chr(13) and line feed Chr(10). That is, 'Coded' will contains multiple lines. RETURNS Number of bytes in 'Coded'. EXAMPLE ClearBuffOne = SPACE(100) ClearBuffTwo = SPACE(100) CodedBuff = SPACE(134) NL = Buffer(2) NL = Chr(13) + Chr(10) ClearBuffOne = "SEE/POP3 Test" + NL + "Bye." + NL + Chr(0) Length = Len(ClearBuffOne) // BASE64 encode Length = seeEncodeBuff(@ClearBuffOne,@CodedBuff, Length) // BASE64 decode Length = seeDecodeBuff(@CodedBuff,@ClearBuffTwo, Length) // ClearBuffTwo should have same text as ClearBuffOne ALSO SEE seeIntegerParam, seeSmtpConnect, and seePop3Connect. SEE4FP Reference Manual Page 9 +--------------+----------------------------------------------------+ | seeErrorText | Get text associated with error code. | +--------------+----------------------------------------------------+ SYNTAX CLONG seeErrorText(CLONG,CLONG,CSTRING,CLONG) // CLONG Chan : Channel Channel // CLONG Code : Error code returned by SEE. // CSTRING @Buffer : Buffer to place error text. // CLONG BufLen : Length of above Buffer. REMARKS The seeErrorText function is used to get the error text associated with an an error code as returned by one of the other SEE functions. When an error occurs, seeErrorText can be used to get the error text so that it can be displayed for the user. EXAMPLE Buffer = SPACE(64) Code = seeSmtpConnect(...) if Code < 0 // error detected Code = seeErrorText(0, Code, @Buffer, 64) ? Left(Buffer,Code) endif SEE4FP Reference Manual Page 10 +----------------+--------------------------------------------------+ | seeExtractText | Extract specified text from buffer. | +----------------+--------------------------------------------------+ SYNTAX CLONG seeExtractText(CSTRING,CSTRING,CSTRING,CLONG) // CSTRING @Source : Text buffer to search. // CSTRING @Text : Text searching for. // CSTRING @Buffer : Buffer for line if found. // CLONG BufSize : Size of 'Buffer'. REMARKS The seeExtractText function is used to search the text buffer 'Source' for text 'Text'. If found, the entire line is copied to 'Buffer', up to a maximum of 'BufSize' bytes. The primary purpose of seeExtractText is to extract header lines from the buffer after calling seeGetEmailLines. The seeExtractText does not require a connection to a SMTP or POP3 server. For an example of use, see the STATUS sample program. RETURNS Number of bytes placed in 'Buffer'. EXAMPLE Temp = SPACE(80) From = SPACE(20) From = "From: " ' search 'Source' for the line containing "From:" Code = seeExtractText(Source, @From, @Temp, 80) ' print line if found if Code > 0 ? Left(Temp,Code) endif ALSO SEE seeGetEmailLines. SEE4FP Reference Manual Page 11 +------------------+------------------------------------------------+ | seeGetEmailCount | Get number of email messages on server. | +------------------+------------------------------------------------+ SYNTAX CLONG seeGetEmailCount(CLONG) // CLONG Chan : Channel Channel REMARKS The seeGetEmailCount function returns the number of messages waiting on the server, independent of whether they have been previously read. If you have disabled the driver AUTO_CALL capability, the message count must be found by Count = seeStatistics(Chan, SEE_GET_MSG_COUNT) after calling seeDriver until it returns 0. Refer to the STATUS sample program for an example of use. RETURNS < 0 : An error has occurred. See the error list >=0 : The number of email messages waiting (if AUTO_CALL was disabled). EXAMPLE // connect to POP3 server Code = seePop3Connect(...) // get # messages waiting Code = seeGetEmailCount(0) ? Str(Code) + " messages waiting" ALSO SEE seeGetEmailLines. SEE4FP Reference Manual Page 12 +-----------------+-------------------------------------------------+ | seeGetEmailFile | Read email message and save to a file. | +-----------------+-------------------------------------------------+ SYNTAX CLONG seeGetEmailFile(CLONG,CLONG,CSTRING,...,CSTRING) // CLONG Chan : channel number // CLONG MsgNbr : header # // CSTRING @EmailName : email filename // CSTRING @EmailDir : directory for email // CSTRING @AttachDir : directory for attachments REMARKS The seeGetEmailFile reads the email message 'MsgNbr', saving it to disk as filename 'EmailName' in directory 'EmailDir', and saving MIME attachments to directory 'AttachDir'. Be sure that the specified directories exist before calling this function. Use '.' to specify the current directory. Also note that a older file of the same name as being saved will be overwritten by the newer file. RETURNS < 0 : An error has occurred. See the error list EXAMPLE ' read message 1 and save as MYMAIL.TXT in ' the current directory Code = seeGetEmailFile(0, 1, "mymail.txt", ".", ".") if Code < 0 ... handle error code endif ALSO SEE seeGetEmailLines. SEE4FP Reference Manual Page 13 +------------------+------------------------------------------------+ | seeGetEmailLines | Read lines from email message. | +------------------+------------------------------------------------+ SYNTAX CLONG seeGetEmailLines(CLONG,...,CLONG,CSTRING,CLONG ) // CLONG Chan : Channel Channel // CLONG MsgNbr : message # // CLONG Lines : # lines // CSTRING @Buffer : buffer for email // CLONG Size : size of buffer REMARKS The seeGetEmailLines function reads all header lines plus the number of body lines specified by the 'Lines' argument into 'Buffer', up to a maximum of 'Size' bytes. The primary purpose of this function is to read the header lines without having to read the entire message. If you have disabled the driver AUTO_CALL capability, the size must be found by Count = seeStatistics(Chan, SEE_GET_BUFFER_COUNT) after calling seeDriver until it returns 0. See the STATUS sample code for an example of use. RETURNS < 0 : An error has occurred. See the error list. >=0 : The number of bytes read (if AUTO_CALL was disabled). EXAMPLE Buffer = SPACE(1024) . . . ' read header lines for email # 1 Code = seeGetEmailLines(0,1,0,@Buffer,1024) ALSO SEE seeGetEmailFile SEE4FP Reference Manual Page 14 +-----------------+-------------------------------------------------+ | seeGetEmailSize | Get size of email message in bytes. | +-----------------+-------------------------------------------------+ SYNTAX CLONG seeGetEmailSize(CLONG,CLONG) // CLONG Chan : channel number // CLONG MsgNbr : message number REMARKS The seeGetEmailSize function returns the size in bytes of the specified message # 'MsgNbr'. seeGetEmailSize returns the size of the entire email message, including any attachments. Note that attachments will be encoded (MIME, UUENCODE, etc.), and thus take up more room than after they are decoded. If you have disabled the driver AUTO_CALL capability, the size must be found by Count = seeStatistics(Chan, SEE_GET_MSG_SIZE) after calling seeDriver until it returns 0. See the READER sample code for an example of use. RETURNS < 0 : An error has occurred. See the error list >=0 : The size of the email in bytes on the server (if AUTO_CALL was disabled). EXAMPLE long FileSize; . . . // get size of email message # 3 FileSize = seeGetEmailSize(0, 3) ALSO SEE seeGetEmailCount. SEE4FP Reference Manual Page 15 +----------------+--------------------------------------------------+ | seeGetEmailUID | Get user ID from the server. | +----------------+--------------------------------------------------+ SYNTAX CLONG seeGetEmailUID(CLONG,CLONG,CSTRING,CLONG) // CLONG Chan : channel number // CLONG MsgNbr : message (-1 for all) # // CSTRING @Buffer : pointer to Buffer // CLONG BufLen : size of buffer REMARKS The seeGetEmailUID function is used to ask the POP3 server for the unique user ID string for a particular email message, or for all email messages on the server. The UID string is always the same for a particular email message, regardless of the email message number. Most POP3 servers can provide such a unique ID string. A few POP3 servers do not provide ID strings. RETURNS < 0 : An error has occurred. See the error list >=0 : The number of bytes in moved into 'Buffer'. (if AUTO_CALL was disabled). EXAMPLE Buffer = SPSACE(2048) // get list of UID's for all mail on the server. Code = seeGetEmailUID(0, -1, @Buffer, 2048) ALSO SEE seeGetEmailCount. SEE4FP Reference Manual Page 16 +-----------------+-------------------------------------------------+ | seeIntegerParam | Sets SEE integer parameter. | +-----------------+-------------------------------------------------+ SYNTAX CLONG seeIntegerParam(CLONG,CLONG,CLONG) // CLONG Chan : channel number // CLONG ParmIndex : parameter index (see below). // CLONG ParmValue : value of parameter to set. REMARKS The seeIntegerParam is used to set an integer parameter which controls the operation of SEE4FP. For more information, refer to the Users Manual. All times are in milliseconds. Pass 1 for TRUE (or YES) and 0 for FALSE (or NO). Parameter Name Default SEE_MIN_RESPONSE_WAIT : 0 SEE_MAX_RESPONSE_WAIT : 25000 SEE_MIN_LINE_WAIT : 0 SEE_MAX_LINE_WAIT : 25000 SEE_CONNECT_WAIT : 60000 SEE_QUOTED_PRINTABLE : 0 SEE_AUTO_CALL_DRIVER : 1 SEE_FILE_PREFIX : 0 SEE_SLEEP_TIME : 50 SEE_MIN_RESPONSE_WAIT is the delay before looking for the server's response. SEE_MAX_RESPONSE_WAIT is the time after which a "time-out" error occurs if the server has not responded. SEE_MIN_LINE_WAIT is the delay before checking if the server is ready to accept the next line of input. SEE_MAX_LINE_WAIT is the time after which a "time-out" error is declared if the server has not responded. SEE_CONNECT_WAIT is the maximum time allowed to complete a connection to the SMTP server. (continued on next page) SEE4FP Reference Manual Page 17 SEE_QUOTED_PRINTABLE controls whether messages are or are not encoded as quoted-printable. Use QUOTED_OFF (0) to disable quoting, QUOTED_PLAIN (1) to enable normal quoting, and QUOTED_HTML (2) to enabled quoting of embedded HTML text. SEE_AUTO_CALL_DRIVER controls whether seeDriver is called automatically (to completion) after seeSmtpConnect or seePop3Connect has been called. Refer to the Users manual for more details on the operation of seeDriver. SEE_SLEEP_TIME is the time SEE sleeps when waiting on a winsock. SEE_FILE_PREFIX controls whether "1-", "2-", etc. is prefixed to the filename of each attachment. If two attachments are named FILEONE.ZIP and FILETWO.ZIP, they will be saved as 1-FILEONE.ZIP and 2-FILETWO.ZIP. Note that Windows 3.1 may truncate long filenames. This feature should always be used unless you are downloading to a directory specifically for downloaded attachments. EXAMPLE // enable quoting Code = seeIntegerParam(Chan, SEE_QUOTED_PRINTABLE, 1) // disable auto call feature Code = seeIntegerParam(Chan, SEE_AUTO_CALL_DRIVER, 0) // enable attachment file prefixes Code = seeIntegerParam(Chan, SEE_FILE_PREFIX, 1) // set maximum response wait to 45 seconds Code = seeIntegerParam(Chan, SEE_MAX_RESPONSE_WAIT, 45000) ALSO SEE seeStringParam. SEE4FP Reference Manual Page 18 +----------------+--------------------------------------------------+ | seePop3Connect | Connects to POP3 Server. | +----------------+--------------------------------------------------+ SYNTAX CLONG seePop3Connect(CLONG,CSTRING,CSTRING,CSTRING) // CLONG Chan : channel number // CSTRING @Pop3Ptr : Pop3 server name // CSTRING @UserPtr : POP3 user name // CSTRING @PassPtr : POP3 password REMARKS The seePop3Connect function establishes a connection with the POP3 server as specified by the Server argument. Your POP3 server name will typically be named "mail.XXX.com" where XXX is your email address, such as name@XXX.com. Your POP3 server name can also be found in the setup information for your normal email client, such as Eudora or Microsoft Outlook. The POP3 server name can also be specified in dotted decimal notation if wanted. For example "10.23.231.1". SEE can not be connected to both the SMTP server and the POP3 server at the same time. Call seeClose to terminate one connection before connecting again. Refer to the SEE4FP Users Manual for more information. RETURNS < 0 : An error has occurred. See the error list. EXAMPLE Code = seePop3Connect(0, "mail.myisp.com", // POP3 server "billbob", // user "xxx") // password ALSO SEE seeSmtpConnect and seeClose. SEE4FP Reference Manual Page 19 +------------+------------------------------------------------------+ | seeRelease | Releases SEE. | +------------+------------------------------------------------------+ SYNTAX CLONG seeRelease(CVOID) REMARKS The seeRelease function releases the SEE system. This should be the very last function called. seeClose should be called for all channels before calling seeRelease. RETURNS < 0 : An error has occurred. Call seeErrorText. EXAMPLE // Initialize SEE for one channel (# 0). Code = seeAttach(1, SEE_KEY_CODE) // // call any SEE function except seeAttach and seeRelease. // // close channel 0 Code = seeClose(0) // Terminate SEE Code = seeRelease() ALSO SEE seeAttach. SEE4FP Reference Manual Page 20 +--------------+----------------------------------------------------+ | seeSendEmail | Sends email and attachments. | +--------------+----------------------------------------------------+ SYNTAX CLONG seeSendEmail(CLONG,CSTRING,...,CSTRING) // CLONG Chan : channel number // CSTRING @To : recipient, separated by commas. // CSTRING @CC : CC list, separated by commas. // CSTRING @BCC : BCC list, separated by commas. // CSTRING @Subj : subject text. // CSTRING @Msg : message or message filename. // CSTRING @Attach : file attachment. REMARKS The seeSendEmail function is used to send email once a connection has been made to your SMTP server after calling seeSmtpConnect. Note that all email addresses (in To, CC, and BCC strings) must be bracketed. For example: "Mike M" The CC and BCC strings may contain multiple email addresses, separated by commas. For example: "Billy Bob,Buster" If the first character of the message (fifth argument) is a '@', then it is considered as the filename which contains the message to send. 'Attach' may contain one or more attachments, separated by commas. For example, "file1.zip,file2.doc". RETURNS < 0 : An error has occurred. See the error list. EXAMPLE seeSendEmail(0, "", // recipient "", // CC list "", // BCC list "Hello", // subject "Call me ASAP!", // message "") // attachment ALSO SEE seeSmtpConnect. SEE4FP Reference Manual Page 21 +----------------+--------------------------------------------------+ | seeSmtpConnect | Connects to SMTP server. | +----------------+--------------------------------------------------+ SYNTAX CLONG seeSmtpConnect(CLONG,CSTRING,CSTRING,CSTRING) // CLONG Chan : channel number // CSTRING @Server : SMTP server. // CSTRING @From : your email addr in brackets. // CSTRING @ReplyTo : email address to reply to. REMARKS The seeSmtpConnect function establishes a connection with the SMTP server as specified by the 'Server' argument. Your SMTP server name will typically be named "mail.XXX.com" where XXX is your email address, such as name@XXX.com. Your SMTP server name can also be found in the setup information for your normal email client, such as Eudora or Microsoft Outlook. The SMTP server name can also be specified in dotted decimal notation if wanted. For example "10.23.231.1". The 'From' string is required and must be enclosed in "<>" brackets, such as "Mike M". The 'ReplyTo' string is optional and is used for the "Reply-To:" header line. If used, the email address must be enclosed in "<>" brackets. SEE can not be connected to both the SMTP server and the POP3 server at the same time. Call seeClose to terminate one connection before connecting again. RETURNS < 0 : An error has occurred. See the error list. EXAMPLE seeSmtpConnect(0, "mail.myisp.com", // my SMTP server "", // my email address "") // no Reply-To seeSmtpConnect(0, "mail.myisp.com", // my SMTP server "", // my email address ") // Reply-To address ALSO SEE seeClose. SEE4FP Reference Manual Page 22 +---------------+---------------------------------------------------+ | seeStatistics | Returns runtime statistics. | +---------------+---------------------------------------------------+ SYNTAX CLONG seeStatistics(CLONG,CLONG) // CLONG Chan : channel number // CLONG Index : specifies which statistic. REMARKS The seeStatistics function is used to return runtime statistics in the SEE DLL. The values of 'Index' are defined in SEE16.CC and SEE32.CC as follows: SEE_GET_VERSION : Gets the SEE version number. SEE_GET_SOCK_ERROR : Gets last socket error. SEE_GET_COUNTER : Gets # times driver called. SEE_GET_RESPONSE : Gets last SMTP response code. SEE_GET_MESSAGE_BYTES_READ : Gets # message bytes read. SEE_GET_ATTACH_BYTES_READ : Gets # attachment bytes read. SEE_GET_TOTAL_BYTES_READ : Gets total of above two. SEE_GET_MESSAGE_BYTES_SENT : Gets # message bytes sent. SEE_GET_ATTACH_BYTES_SENT : Gets # attachment bytes sent. SEE_GET_TOTAL_BYTES_SENT : Gets total of above two. SEE_GET_MSG_COUNT : Gets # emails waiting. SEE_GET_MSG_SIZE : Gets size of email. SEE_GET_BUFFER_COUNT : Gets # bytes in buffer for seeGetEmailLines. SEE_GET_CONNECT_STATUS : Returns TRUE if connected. SEE_GET_VERIFY_STATUS : Returns seeVerifyUser status. SEE_GET_ATTACH_COUNT : Gets # attachments received. The number of message bytes sent will usually be larger than your message size because of SMTP protocol overhead. The number of attachment bytes sent will be at least one-third larger than the actual attachment since every 3 bytes are encoded as 4 7-bit ASCII bytes before being transmitted. The purpose of "...BYTES_READ" and "...BYTES_SENT" is to provide the ability to track the transmission progress of large messages and attachments. See the READER example. EXAMPLE ' get total message and attachment bytes transmitted. Code = seeStatistics(0, SEE_GET_TOTAL_BYTES_SENT) ALSE SEE seeDriver, seeIntegerParam, and seeStringParam. SEE4FP Reference Manual Page 23 +----------------+--------------------------------------------------+ | seeStringParam | Sets SEE string parameter. | +----------------+--------------------------------------------------+ SYNTAX CLONG seeStringParam(CLONG,CLONG,CSTRING) // CLONG Chan : channel number // CLONG ParamName : index of parameter. // CSTRING @ParamString : parameter string. REMARKS The seeStringParam function is used to set a string parameter as defined in SEE16.CC and SEE32.CC. For more information, refer to the Users Manual. SEE_LOG_FILE : Specifies the log filename. SEE_SET_REPLY : Sets the "Reply To" string. SEE_SET_HEADER : Adds header line(s). The log file is used to debug a SMTP/POP3 session. Be advised that log files can be quite large. Don't use them unless necessary. Use SEE_SET_REPLY to change the "Reply-To:" header after connecting to the server, just before sending an email. Use SEE_SET_HEADER to add one or more header lines. Each header line except the last should end with a carriage return line feed pair. EXAMPLE X = SPACE(100) ' specify a log file. Code = seeStringParam(0, SEE_LOG_FILE, "mytest.log") ' specify "Reply-To:" address Code = seeStringParam(0, SEE_SET_REPLY, "") ' add our header lines X="X-Priority: Normal"+CHR(13)+CHR(10)+ "Sender: FromUs" Code = seeStringParam(0, SEE_SET_HEADER, X) ALSO SEE seeIntegerParam. SEE4FP Reference Manual Page 24 +-----------------+-------------------------------------------------+ | seeVerifyFormat | Check email address format. | +-----------------+-------------------------------------------------+ SYNTAX CLONG seeVerifyFormat(CSTRING) // CSTRING @Text : email address to check. REMARKS The seeVerifyFormat function is used to test an individual email address for proper formatting. If this function returns 0 or above, then the email address is properly formatted. But, if this function returns a negative value, the email address is either badly formatted, or it uses characters (such as '') that are not normally used as part of an email address. Note that left and right brackets ('<' and '>') must surround the email address. EXAMPLE Buffer = SPACE(80) . . . Code = seeVerifyFormat("Billy E. Bob") if Code < 0 Code = seeErrorText(0,Code,Buffer,80) ? "Email address error : " + Left(Buffer,Code) endif ALSO SEE seeErrorText. SEE4FP Reference Manual Page 25 +---------------+---------------------------------------------------+ | seeVerifyUser | Verify email address. | +---------------+---------------------------------------------------+ SYNTAX CLONG seeVerifyUser(CLONG,CSTRING) // CLONG Chan : channel number // CSTRING @Text : email address to verify. REMARKS The seeVerifyUser function is used to verify an individual email address with the email server which "owns" the email address. seeVerify will connect to the specified server and request verification of the user. Some SMTP servers may refuse connection of any client not directly connected to them or may refuse all "verify user" requests. Web based email servers such as hotmail.com may refuse all SMTP connections. Note that you connect to the remote SMTP server rather than the SMTP server that you use to send email. For example, to verify msc@traveller.com, you must first connect to the SMTP server "mail.traveller.com" then call SeeVerifyUser("msc"). EXAMPLE SmtpServer = SPACE(65) User = SPACE(40) Buffer = SPACE(128) SmtpServer = "mail.traveller.com" Usr = "msc" Code = seeSmtpConnect(0,@SmtpServer, ...) . . . Code = seeVerifyUser(0,@UserPtr) if Code = 0 ' display last server response Code = seeDebug(0,SEE_GET_LAST_RESPONSE, @Buffer, 128) ? Left(User,Code) + " is NOT verified" else ? Left(User,Code) + " is verified" endif ALSO SEE seeErrorText and seeDebug. SEE4FP Reference Manual Page 26